<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Conventions - Boost.Outcome documentation</title>
<link rel="stylesheet" href="../../css/boost.css" type="text/css">
<meta name="generator" content="Hugo 0.52 with Boostdoc theme">
<meta name="viewport" content="width=device-width,initial-scale=1.0"/>

<link rel="icon" href="../../images/favicon.ico" type="image/ico"/>
<body><div class="spirit-nav">
<a accesskey="p" href="../../tutorial/essential/coroutines/co_await.html"><img src="../../images/prev.png" alt="Prev"></a>
    <a accesskey="u" href="../../tutorial/essential.html"><img src="../../images/up.png" alt="Up"></a>
    <a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../../tutorial/advanced.html"><img src="../../images/next.png" alt="Next"></a></div><div id="content">

  <div class="titlepage"><div><div><h1 style="clear: both">Conventions</h1></div></div></div>


<p>You now know everything you need to get started with using Outcome
immediately.</p>

<p>The initial temptation for most beginners will be to use a bespoke
strongly typed enumeration on a case by case basis i.e. a &ldquo;once off&rdquo;
custom <code>E</code> type. This is usually due to experience in other languages
with sum types e.g. Rust, Haskell, Swift etc.</p>

<p>However this is C++! Not Rust, not Swift, not Haskell! I must caution you to always avoid using
custom <code>E</code> types in public APIs. The reason is that every time
library A using custom <code>E1</code> type must interface with library B
using custom <code>E2</code> type, you must map between those <code>E1</code> and <code>E2</code>
types.</p>

<p>This is information lossy, i.e. fidelity of failure gets lost
after multiple translations. It involves writing, and then
<em>maintaining</em>, a lot of annoying boilerplate. It leaks internal
implementation detail, and fails to separate concerns. And one
cannot use <a href="../../reference/macros/tryv.html" class="api-reference"><code>BOOST_OUTCOME_TRYV(expr)/BOOST_OUTCOME_TRY(expr)</code></a>

if there is no convertibility between <code>E</code> types.</p>

<p>The C++ 11 standard library, and Boost,
specifically ships <code>&lt;system_error&gt;</code> for the purpose of wrapping up
individual custom <code>E</code> types into a generic framework, where disparate
custom <code>E</code> types can discover and interact with one another.
That ships with every C++ compiler.</p>

<p>For all these reasons, this is why <code>result</code> and <code>outcome</code> default
the <code>EC</code> type to error code. You should leave that default alone
where possible.</p>

<hr />

<h3 id="tl-dr">tl;dr;</h3>

<p>Please <a href="../../motivation/plug_error_code.html">plug your library into <code>std::error_code</code></a>,
or <a href="../../experimental.html">equivalent</a>, and do not expose
custom <code>E</code> types in ANY public API. <code>result</code> and <code>outcome</code> default
<code>EC</code> to an error code for good reason.</p>



        </div><p><small>Last revised: February 09, 2019 at 15:18:26 UTC</small></p>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../../tutorial/essential/coroutines/co_await.html"><img src="../../images/prev.png" alt="Prev"></a>
    <a accesskey="u" href="../../tutorial/essential.html"><img src="../../images/up.png" alt="Up"></a>
    <a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../../tutorial/advanced.html"><img src="../../images/next.png" alt="Next"></a></div></body>
</html>
